home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / lollipop / head.tex < prev    next >
Text File  |  1993-01-28  |  4KB  |  137 lines
  1. % Head.tex copyright 1992 Victor Eijkhout
  2. %
  3. \Chapter Headings
  4.  
  5. Headings for sections, chapters, and such, are an essential part of
  6. any \TeX\ macro package. In Lollipop they are maybe a bit less
  7. special: all options for headings are general options, meaning that
  8. they also apply to text blocks and lists. There are only two things
  9. that distinguish headings:
  10.  
  11. \Enumerate
  12. \item there will be no page break after a heading;
  13. \item there is no closing command for a heading.
  14. \>
  15.  
  16. \Section[sec:head:examples] Examples
  17.  
  18. Headings are defined by \refcs{DefineHeading}.
  19. The most obvious element in a heading is the title, marked by the
  20. option \refopt{title}. The title is anything that follows the heading
  21. command, upto the first empty line.
  22.  
  23. \Ver>\SomeHeading Some title
  24.  
  25. And some text following it.<Rev
  26.  
  27. \ImpNote
  28. Titles can also be terminated by \cs{par}, but knowledge of this is
  29. not encouraged. See further~\ref[imp:title:delimiting].
  30. \ImpNoteStop
  31.  
  32. The title has to be
  33. included in a line or a textcolumn for proper handling (see
  34. also section~\ref[sec:opt:traps]). For titles that do not exceed one
  35. line, the \opt{line} option suffices (section~\ref[sec:opt:line]); if a
  36. title is possibly more than one line long, the \opt{textcolumn} option
  37. has to be used (section~\ref[sec:opt:textcolumn].
  38.  
  39. \Example 
  40. \DefineHeading:TestSection Style:bold
  41.     line:start TestSectionCounter Spaces:2 title line:stop
  42.     Stop
  43. \TestSection The Title
  44.  
  45. The text after the heading.
  46. \ExampleStop
  47.  
  48. By default, the text after a heading is indented. Overriding this
  49. default behaviour is done with the option \refopt{indentafter}.
  50.  
  51. \Example
  52. \AlwaysIndent:no % as a default, don't indent paragraphs
  53. \DefineHeading:TestSection Style:bold
  54.     line:start TestSectionCounter Spaces:2 title line:stop
  55.     indentafter:yes Stop
  56. \TestSection The Title
  57.  
  58. The text after the heading.\par
  59. The second paragraph after the heading
  60. \ExampleStop
  61.  
  62. Usually headings come in a hierarchy, where the counter of one type,
  63. for instance a subsection, is reset everytime the counter of a higer
  64. level  is stepped. In \Lollipop, this subordinating of headings is
  65. done by declaring one counter to be governed by another (counters
  66. are explained in full detail in section~\ref[sec:counters]). 
  67.  
  68. \Example
  69. \DefineHeading:TestChapter Style:bold
  70.     line:start TestChapterCounter Spaces:1 title line:stop
  71.     Stop
  72. \DefineHeading:TestSection Style:italic
  73.     line:start TestChapterCounter : TestSectionCounter . Spaces:1
  74.         title line:stop Stop
  75. \GoverningCounter:TestSection=TestChapter
  76.  
  77. \TestChapter Level One Heading\par
  78. \TestSection Level Two Heading\par
  79. Some text.
  80. \TestSection Level Two again\par
  81. More text.
  82. \TestChapter Level One is Stepped\par
  83. \TestSection Level Two\par
  84. Again text.
  85. \ExampleStop
  86.  
  87. Headings will often wind up in a table of contents. For this, the
  88. table of contents will have to be declared:
  89. \Ver>\DefineExternalFile:contents=toc<Rev
  90. and its formatting will have to be specified, but also every
  91. construct that writes to this file has to be declared as such.
  92.  
  93. \Ver>\DefineHeading:TestSection
  94.     [...]
  95.     external:contents title external:stop
  96.     Stop<Rev
  97.  
  98. Usually, the title is all that has to be written out (the counter
  99. value is written by default), but the possibility exists for writing
  100. out other information as well. See section~\ref[sec:ext-option].
  101.  
  102. \ImpNote 
  103.  
  104. \iSection Page break prevention after titles
  105.  
  106. Simple prevention of page breaks is done by
  107. \Ver>
  108. \add@Heading@default{\def\@afterpenalty{\penalty\@M}}<Rev
  109. The \cs{@afterpenalty} is used in \cs{gen@open}
  110. (see~\ref[imp:gen:open:close]).
  111.  
  112. A conditional \cs{if@headed} is defined, which is only true after
  113. headings:
  114. \Ver>
  115. \newif\if@headed
  116. \add@generic@default{\add@after@command{\@headedno}}
  117. \add@Heading@default{\add@after@command{\@headedyes}}<Rev
  118.  
  119. This is used in \cs{outer@start@commands} to prevent a page break
  120. between a heading and a subsequent generic construct.
  121. \Ver>
  122.         \nxp\if@headed\nxp\else
  123.             \ifforced@break@before\@beforepenalty
  124.             \else\nxp\ifnum\lastpenalty=\z@
  125.                          \@beforepenalty
  126.                  \nxp\fi
  127.             \fi
  128.         \nxp\fi<Rev
  129.  
  130. If \cs{if@headed} is true, then no penalty at all is placed, 
  131. so that the
  132. trailing infinite penalty of the heading will dominate page
  133. breaking at this point.
  134.  
  135. \ImpNoteStop
  136.  
  137.